<!doctype html>

<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>mockmatchers.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>

<div class="clear"></div>

<h2><a href="closure_goog_testing_mockmatchers.js.html">mockmatchers.js</a></h2>

<pre class="prettyprint lang-js">
<a name="line1"></a>// Copyright 2008 The Closure Library Authors. All Rights Reserved.
<a name="line2"></a>//
<a name="line3"></a>// Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
<a name="line4"></a>// you may not use this file except in compliance with the License.
<a name="line5"></a>// You may obtain a copy of the License at
<a name="line6"></a>//
<a name="line7"></a>//      http://www.apache.org/licenses/LICENSE-2.0
<a name="line8"></a>//
<a name="line9"></a>// Unless required by applicable law or agreed to in writing, software
<a name="line10"></a>// distributed under the License is distributed on an &quot;AS-IS&quot; BASIS,
<a name="line11"></a>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<a name="line12"></a>// See the License for the specific language governing permissions and
<a name="line13"></a>// limitations under the License.
<a name="line14"></a>
<a name="line15"></a>/**
<a name="line16"></a> * @fileoverview Matchers to be used with the mock utilities.  They allow for
<a name="line17"></a> * flexible matching by type.  Custom matchers can be created by passing a
<a name="line18"></a> * matcher function into an ArgumentMatcher instance.
<a name="line19"></a> *
<a name="line20"></a> * For examples, please see the unit test.
<a name="line21"></a> *
<a name="line22"></a> */
<a name="line23"></a>
<a name="line24"></a>
<a name="line25"></a>goog.provide(&#39;goog.testing.mockmatchers&#39;);
<a name="line26"></a>goog.provide(&#39;goog.testing.mockmatchers.ArgumentMatcher&#39;);
<a name="line27"></a>goog.provide(&#39;goog.testing.mockmatchers.IgnoreArgument&#39;);
<a name="line28"></a>goog.provide(&#39;goog.testing.mockmatchers.InstanceOf&#39;);
<a name="line29"></a>goog.provide(&#39;goog.testing.mockmatchers.ObjectEquals&#39;);
<a name="line30"></a>goog.provide(&#39;goog.testing.mockmatchers.RegexpMatch&#39;);
<a name="line31"></a>goog.provide(&#39;goog.testing.mockmatchers.SaveArgument&#39;);
<a name="line32"></a>goog.provide(&#39;goog.testing.mockmatchers.TypeOf&#39;);
<a name="line33"></a>
<a name="line34"></a>goog.require(&#39;goog.array&#39;);
<a name="line35"></a>goog.require(&#39;goog.dom&#39;);
<a name="line36"></a>goog.require(&#39;goog.testing.asserts&#39;);
<a name="line37"></a>
<a name="line38"></a>
<a name="line39"></a>
<a name="line40"></a>/**
<a name="line41"></a> * A simple interface for executing argument matching.  A match in this case is
<a name="line42"></a> * testing to see if a supplied object fits a given criteria.  True is returned
<a name="line43"></a> * if the given criteria is met.
<a name="line44"></a> * @param {Function=} opt_matchFn A function that evaluates a given argument
<a name="line45"></a> *     and returns true if it meets a given criteria.
<a name="line46"></a> * @param {?string=} opt_matchName The name expressing intent as part of
<a name="line47"></a> *      an error message for when a match fails.
<a name="line48"></a> * @constructor
<a name="line49"></a> */
<a name="line50"></a>goog.testing.mockmatchers.ArgumentMatcher =
<a name="line51"></a>    function(opt_matchFn, opt_matchName) {
<a name="line52"></a>  /**
<a name="line53"></a>   * A function that evaluates a given argument and returns true if it meets a
<a name="line54"></a>   * given criteria.
<a name="line55"></a>   * @type {Function}
<a name="line56"></a>   * @private
<a name="line57"></a>   */
<a name="line58"></a>  this.matchFn_ = opt_matchFn || null;
<a name="line59"></a>
<a name="line60"></a>  /**
<a name="line61"></a>   * A string indicating the match intent (e.g. isBoolean or isString).
<a name="line62"></a>   * @type {?string}
<a name="line63"></a>   * @private
<a name="line64"></a>   */
<a name="line65"></a>  this.matchName_ = opt_matchName || null;
<a name="line66"></a>};
<a name="line67"></a>
<a name="line68"></a>
<a name="line69"></a>/**
<a name="line70"></a> * A function that takes a match argument and an optional MockExpectation
<a name="line71"></a> * which (if provided) will get error information and returns whether or
<a name="line72"></a> * not it matches.
<a name="line73"></a> * @param {*} toVerify The argument that should be verified.
<a name="line74"></a> * @param {goog.testing.MockExpectation?=} opt_expectation The expectation
<a name="line75"></a> *     for this match.
<a name="line76"></a> * @return {boolean} Whether or not a given argument passes verification.
<a name="line77"></a> */
<a name="line78"></a>goog.testing.mockmatchers.ArgumentMatcher.prototype.matches =
<a name="line79"></a>    function(toVerify, opt_expectation) {
<a name="line80"></a>  if (this.matchFn_) {
<a name="line81"></a>    var isamatch = this.matchFn_(toVerify);
<a name="line82"></a>    if (!isamatch &amp;&amp; opt_expectation) {
<a name="line83"></a>      if (this.matchName_) {
<a name="line84"></a>        opt_expectation.addErrorMessage(&#39;Expected: &#39; +
<a name="line85"></a>            this.matchName_ + &#39; but was: &#39; + _displayStringForValue(toVerify));
<a name="line86"></a>      } else {
<a name="line87"></a>        opt_expectation.addErrorMessage(&#39;Expected: missing mockmatcher&#39; +
<a name="line88"></a>            &#39; description but was: &#39; +
<a name="line89"></a>            _displayStringForValue(toVerify));
<a name="line90"></a>      }
<a name="line91"></a>    }
<a name="line92"></a>    return isamatch;
<a name="line93"></a>  } else {
<a name="line94"></a>    throw Error(&#39;No match function defined for this mock matcher&#39;);
<a name="line95"></a>  }
<a name="line96"></a>};
<a name="line97"></a>
<a name="line98"></a>
<a name="line99"></a>
<a name="line100"></a>/**
<a name="line101"></a> * A matcher that verifies that an argument is an instance of a given class.
<a name="line102"></a> * @param {Function} ctor The class that will be used for verification.
<a name="line103"></a> * @constructor
<a name="line104"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line105"></a> */
<a name="line106"></a>goog.testing.mockmatchers.InstanceOf = function(ctor) {
<a name="line107"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(this,
<a name="line108"></a>      function(obj) {
<a name="line109"></a>        return obj instanceof ctor;
<a name="line110"></a>      // NOTE: Browser differences on ctor.toString() output
<a name="line111"></a>      // make using that here problematic. So for now, just let
<a name="line112"></a>      // people know the instanceOf() failed without providing
<a name="line113"></a>      // browser specific details...
<a name="line114"></a>      }, &#39;instanceOf()&#39;);
<a name="line115"></a>};
<a name="line116"></a>goog.inherits(goog.testing.mockmatchers.InstanceOf,
<a name="line117"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line118"></a>
<a name="line119"></a>
<a name="line120"></a>
<a name="line121"></a>/**
<a name="line122"></a> * A matcher that verifies that an argument is of a given type (e.g. &quot;object&quot;).
<a name="line123"></a> * @param {string} type The type that a given argument must have.
<a name="line124"></a> * @constructor
<a name="line125"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line126"></a> */
<a name="line127"></a>goog.testing.mockmatchers.TypeOf = function(type) {
<a name="line128"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(this,
<a name="line129"></a>      function(obj) {
<a name="line130"></a>        return goog.typeOf(obj) == type;
<a name="line131"></a>      }, &#39;typeOf(&#39; + type + &#39;)&#39;);
<a name="line132"></a>};
<a name="line133"></a>goog.inherits(goog.testing.mockmatchers.TypeOf,
<a name="line134"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line135"></a>
<a name="line136"></a>
<a name="line137"></a>
<a name="line138"></a>/**
<a name="line139"></a> * A matcher that verifies that an argument matches a given RegExp.
<a name="line140"></a> * @param {RegExp} regexp The regular expression that the argument must match.
<a name="line141"></a> * @constructor
<a name="line142"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line143"></a> */
<a name="line144"></a>goog.testing.mockmatchers.RegexpMatch = function(regexp) {
<a name="line145"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(this,
<a name="line146"></a>      function(str) {
<a name="line147"></a>        return regexp.test(str);
<a name="line148"></a>      }, &#39;match(&#39; + regexp + &#39;)&#39;);
<a name="line149"></a>};
<a name="line150"></a>goog.inherits(goog.testing.mockmatchers.RegexpMatch,
<a name="line151"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line152"></a>
<a name="line153"></a>
<a name="line154"></a>
<a name="line155"></a>/**
<a name="line156"></a> * A matcher that always returns true. It is useful when the user does not care
<a name="line157"></a> * for some arguments.
<a name="line158"></a> * For example: mockFunction(&#39;username&#39;, &#39;password&#39;, IgnoreArgument);
<a name="line159"></a> * @constructor
<a name="line160"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line161"></a> */
<a name="line162"></a>goog.testing.mockmatchers.IgnoreArgument = function() {
<a name="line163"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(this,
<a name="line164"></a>      function() {
<a name="line165"></a>        return true;
<a name="line166"></a>      }, &#39;true&#39;);
<a name="line167"></a>};
<a name="line168"></a>goog.inherits(goog.testing.mockmatchers.IgnoreArgument,
<a name="line169"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line170"></a>
<a name="line171"></a>
<a name="line172"></a>
<a name="line173"></a>/**
<a name="line174"></a> * A matcher that verifies that the argument is an object that equals the given
<a name="line175"></a> * expected object, using a deep comparison.
<a name="line176"></a> * @param {Object} expectedObject An object to match against when
<a name="line177"></a> *     verifying the argument.
<a name="line178"></a> * @constructor
<a name="line179"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line180"></a> */
<a name="line181"></a>goog.testing.mockmatchers.ObjectEquals = function(expectedObject) {
<a name="line182"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(this,
<a name="line183"></a>      function(matchObject) {
<a name="line184"></a>        assertObjectEquals(&#39;Expected equal objects&#39;, expectedObject,
<a name="line185"></a>            matchObject);
<a name="line186"></a>        return true;
<a name="line187"></a>      }, &#39;objectEquals(&#39; + expectedObject + &#39;)&#39;);
<a name="line188"></a>};
<a name="line189"></a>goog.inherits(goog.testing.mockmatchers.ObjectEquals,
<a name="line190"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line191"></a>
<a name="line192"></a>
<a name="line193"></a>/** @override */
<a name="line194"></a>goog.testing.mockmatchers.ObjectEquals.prototype.matches =
<a name="line195"></a>    function(toVerify, opt_expectation) {
<a name="line196"></a>  // Override the default matches implementation to capture the exception thrown
<a name="line197"></a>  // by assertObjectEquals (if any) and add that message to the expectation.
<a name="line198"></a>  try {
<a name="line199"></a>    return goog.testing.mockmatchers.ObjectEquals.superClass_.matches.call(
<a name="line200"></a>        this, toVerify, opt_expectation);
<a name="line201"></a>  } catch (e) {
<a name="line202"></a>    if (opt_expectation) {
<a name="line203"></a>      opt_expectation.addErrorMessage(e.message);
<a name="line204"></a>    }
<a name="line205"></a>    return false;
<a name="line206"></a>  }
<a name="line207"></a>};
<a name="line208"></a>
<a name="line209"></a>
<a name="line210"></a>
<a name="line211"></a>/**
<a name="line212"></a> * A matcher that saves the argument that it is verifying so that your unit test
<a name="line213"></a> * can perform extra tests with this argument later.  For example, if the
<a name="line214"></a> * argument is a callback method, the unit test can then later call this
<a name="line215"></a> * callback to test the asynchronous portion of the call.
<a name="line216"></a> * @param {goog.testing.mockmatchers.ArgumentMatcher|Function=} opt_matcher
<a name="line217"></a> *     Argument matcher or matching function that will be used to validate the
<a name="line218"></a> *     argument.  By default, argument will always be valid.
<a name="line219"></a> * @param {?string=} opt_matchName The name expressing intent as part of
<a name="line220"></a> *      an error message for when a match fails.
<a name="line221"></a> * @constructor
<a name="line222"></a> * @extends {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line223"></a> */
<a name="line224"></a>goog.testing.mockmatchers.SaveArgument = function(opt_matcher, opt_matchName) {
<a name="line225"></a>  goog.testing.mockmatchers.ArgumentMatcher.call(
<a name="line226"></a>      this, /** @type {Function} */ (opt_matcher), opt_matchName);
<a name="line227"></a>
<a name="line228"></a>  if (opt_matcher instanceof goog.testing.mockmatchers.ArgumentMatcher) {
<a name="line229"></a>    /**
<a name="line230"></a>     * Delegate match requests to this matcher.
<a name="line231"></a>     * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line232"></a>     * @private
<a name="line233"></a>     */
<a name="line234"></a>    this.delegateMatcher_ = opt_matcher;
<a name="line235"></a>  } else if (!opt_matcher) {
<a name="line236"></a>    this.delegateMatcher_ = goog.testing.mockmatchers.ignoreArgument;
<a name="line237"></a>  }
<a name="line238"></a>};
<a name="line239"></a>goog.inherits(goog.testing.mockmatchers.SaveArgument,
<a name="line240"></a>    goog.testing.mockmatchers.ArgumentMatcher);
<a name="line241"></a>
<a name="line242"></a>
<a name="line243"></a>/** @override */
<a name="line244"></a>goog.testing.mockmatchers.SaveArgument.prototype.matches = function(
<a name="line245"></a>    toVerify, opt_expectation) {
<a name="line246"></a>  this.arg = toVerify;
<a name="line247"></a>  if (this.delegateMatcher_) {
<a name="line248"></a>    return this.delegateMatcher_.matches(toVerify, opt_expectation);
<a name="line249"></a>  }
<a name="line250"></a>  return goog.testing.mockmatchers.SaveArgument.superClass_.matches.call(
<a name="line251"></a>          this, toVerify, opt_expectation);
<a name="line252"></a>};
<a name="line253"></a>
<a name="line254"></a>
<a name="line255"></a>/**
<a name="line256"></a> * Saved argument that was verified.
<a name="line257"></a> * @type {*}
<a name="line258"></a> */
<a name="line259"></a>goog.testing.mockmatchers.SaveArgument.prototype.arg;
<a name="line260"></a>
<a name="line261"></a>
<a name="line262"></a>/**
<a name="line263"></a> * An instance of the IgnoreArgument matcher. Returns true for all matches.
<a name="line264"></a> * @type {goog.testing.mockmatchers.IgnoreArgument}
<a name="line265"></a> */
<a name="line266"></a>goog.testing.mockmatchers.ignoreArgument =
<a name="line267"></a>    new goog.testing.mockmatchers.IgnoreArgument();
<a name="line268"></a>
<a name="line269"></a>
<a name="line270"></a>/**
<a name="line271"></a> * A matcher that verifies that an argument is an array.
<a name="line272"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line273"></a> */
<a name="line274"></a>goog.testing.mockmatchers.isArray =
<a name="line275"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isArray,
<a name="line276"></a>        &#39;isArray&#39;);
<a name="line277"></a>
<a name="line278"></a>
<a name="line279"></a>/**
<a name="line280"></a> * A matcher that verifies that an argument is a array-like.  A NodeList is an
<a name="line281"></a> * example of a collection that is very close to an array.
<a name="line282"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line283"></a> */
<a name="line284"></a>goog.testing.mockmatchers.isArrayLike =
<a name="line285"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isArrayLike,
<a name="line286"></a>        &#39;isArrayLike&#39;);
<a name="line287"></a>
<a name="line288"></a>
<a name="line289"></a>/**
<a name="line290"></a> * A matcher that verifies that an argument is a date-like.
<a name="line291"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line292"></a> */
<a name="line293"></a>goog.testing.mockmatchers.isDateLike =
<a name="line294"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isDateLike,
<a name="line295"></a>        &#39;isDateLike&#39;);
<a name="line296"></a>
<a name="line297"></a>
<a name="line298"></a>/**
<a name="line299"></a> * A matcher that verifies that an argument is a string.
<a name="line300"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line301"></a> */
<a name="line302"></a>goog.testing.mockmatchers.isString =
<a name="line303"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isString,
<a name="line304"></a>        &#39;isString&#39;);
<a name="line305"></a>
<a name="line306"></a>
<a name="line307"></a>/**
<a name="line308"></a> * A matcher that verifies that an argument is a boolean.
<a name="line309"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line310"></a> */
<a name="line311"></a>goog.testing.mockmatchers.isBoolean =
<a name="line312"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isBoolean,
<a name="line313"></a>        &#39;isBoolean&#39;);
<a name="line314"></a>
<a name="line315"></a>
<a name="line316"></a>/**
<a name="line317"></a> * A matcher that verifies that an argument is a number.
<a name="line318"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line319"></a> */
<a name="line320"></a>goog.testing.mockmatchers.isNumber =
<a name="line321"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isNumber,
<a name="line322"></a>        &#39;isNumber&#39;);
<a name="line323"></a>
<a name="line324"></a>
<a name="line325"></a>/**
<a name="line326"></a> * A matcher that verifies that an argument is a function.
<a name="line327"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line328"></a> */
<a name="line329"></a>goog.testing.mockmatchers.isFunction =
<a name="line330"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isFunction,
<a name="line331"></a>        &#39;isFunction&#39;);
<a name="line332"></a>
<a name="line333"></a>
<a name="line334"></a>/**
<a name="line335"></a> * A matcher that verifies that an argument is an object.
<a name="line336"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line337"></a> */
<a name="line338"></a>goog.testing.mockmatchers.isObject =
<a name="line339"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.isObject,
<a name="line340"></a>        &#39;isObject&#39;);
<a name="line341"></a>
<a name="line342"></a>
<a name="line343"></a>/**
<a name="line344"></a> * A matcher that verifies that an argument is like a DOM node.
<a name="line345"></a> * @type {goog.testing.mockmatchers.ArgumentMatcher}
<a name="line346"></a> */
<a name="line347"></a>goog.testing.mockmatchers.isNodeLike =
<a name="line348"></a>    new goog.testing.mockmatchers.ArgumentMatcher(goog.dom.isNodeLike,
<a name="line349"></a>        &#39;isNodeLike&#39;);
<a name="line350"></a>
<a name="line351"></a>
<a name="line352"></a>/**
<a name="line353"></a> * A function that checks to see if an array matches a given set of
<a name="line354"></a> * expectations.  The expectations array can be a mix of ArgumentMatcher
<a name="line355"></a> * implementations and values.  True will be returned if values are identical or
<a name="line356"></a> * if a matcher returns a positive result.
<a name="line357"></a> * @param {Array} expectedArr An array of expectations which can be either
<a name="line358"></a> *     values to check for equality or ArgumentMatchers.
<a name="line359"></a> * @param {Array} arr The array to match.
<a name="line360"></a> * @param {goog.testing.MockExpectation?=} opt_expectation The expectation
<a name="line361"></a> *     for this match.
<a name="line362"></a> * @return {boolean} Whether or not the given array matches the expectations.
<a name="line363"></a> */
<a name="line364"></a>goog.testing.mockmatchers.flexibleArrayMatcher =
<a name="line365"></a>    function(expectedArr, arr, opt_expectation) {
<a name="line366"></a>  return goog.array.equals(expectedArr, arr, function(a, b) {
<a name="line367"></a>    var errCount = 0;
<a name="line368"></a>    if (opt_expectation) {
<a name="line369"></a>      errCount = opt_expectation.getErrorMessageCount();
<a name="line370"></a>    }
<a name="line371"></a>    var isamatch = a === b ||
<a name="line372"></a>        a instanceof goog.testing.mockmatchers.ArgumentMatcher &amp;&amp;
<a name="line373"></a>        a.matches(b, opt_expectation);
<a name="line374"></a>    var failureMessage = null;
<a name="line375"></a>    if (!isamatch) {
<a name="line376"></a>      failureMessage = goog.testing.asserts.findDifferences(a, b);
<a name="line377"></a>      isamatch = !failureMessage;
<a name="line378"></a>    }
<a name="line379"></a>    if (!isamatch &amp;&amp; opt_expectation) {
<a name="line380"></a>      // If the error count changed, the match sent out an error
<a name="line381"></a>      // message. If the error count has not changed, then
<a name="line382"></a>      // we need to send out an error message...
<a name="line383"></a>      if (errCount == opt_expectation.getErrorMessageCount()) {
<a name="line384"></a>        // Use the _displayStringForValue() from assert.js
<a name="line385"></a>        // for consistency...
<a name="line386"></a>        if (!failureMessage) {
<a name="line387"></a>          failureMessage = &#39;Expected: &#39; + _displayStringForValue(a) +
<a name="line388"></a>              &#39; but was: &#39; + _displayStringForValue(b);
<a name="line389"></a>        }
<a name="line390"></a>        opt_expectation.addErrorMessage(failureMessage);
<a name="line391"></a>      }
<a name="line392"></a>    }
<a name="line393"></a>    return isamatch;
<a name="line394"></a>  });
<a name="line395"></a>};
</pre>


</body>
</html>
